home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 38 / Amiga Format CD38 (1999-03-15)(Future Publishing)(GB)(Track 1 of 3)[!][issue 1999-04].iso / -in_the_mag- / reader_requests / dice_v3.15 / doc / stdio.doc < prev    next >
Text File  |  1999-01-26  |  57KB  |  2,454 lines
  1.  
  2.     STDIO.DOC (c)Copyright 1990, Matthew Dillon, All Rights Reserved
  3.  
  4. TABLE OF CONTENTS
  5.  
  6. c.lib/stdio/clearerr
  7. c.lib/stdio/fclose
  8. c.lib/stdio/fdopen
  9. c.lib/stdio/feof
  10. c.lib/stdio/ferror
  11. c.lib/stdio/fflush
  12. c.lib/stdio/fgetc
  13. c.lib/stdio/fgetpos
  14. c.lib/stdio/fgets
  15. c.lib/stdio/filbuf
  16. c.lib/stdio/fileno
  17. c.lib/stdio/fopen
  18. c.lib/stdio/fprintf
  19. c.lib/stdio/fputc
  20. c.lib/stdio/fputs
  21. c.lib/stdio/fread
  22. c.lib/stdio/freopen
  23. c.lib/stdio/fscanf
  24. c.lib/stdio/fseek
  25. c.lib/stdio/fsetpos
  26. c.lib/stdio/ftell
  27. c.lib/stdio/fwrite
  28. c.lib/stdio/getc
  29. c.lib/stdio/getchar
  30. c.lib/stdio/gets
  31. c.lib/stdio/perror
  32. c.lib/stdio/pfmt
  33. c.lib/stdio/printf
  34. c.lib/stdio/putc
  35. c.lib/stdio/putchar
  36. c.lib/stdio/puts
  37. c.lib/stdio/remove
  38. c.lib/stdio/rename
  39. c.lib/stdio/rewind
  40. c.lib/stdio/scanf
  41. c.lib/stdio/setbuf
  42. c.lib/stdio/setvbuf
  43. c.lib/stdio/sprintf
  44. c.lib/stdio/sscanf
  45. c.lib/stdio/stdin
  46. c.lib/stdio/stdout
  47. c.lib/stdio/stderr
  48. c.lib/stdio/tmpfile
  49. c.lib/stdio/tmpnam
  50. c.lib/stdio/ungetc
  51. c.lib/stdio/vfprintf
  52. c.lib/stdio/vprintf
  53. c.lib/stdio/vsprintf
  54.  
  55.  
  56. stdio/file_pointer                        stdio/file_pointer
  57.  
  58.     A file pointer is the basis for STDIO, a standard file buffering
  59.     package across all versions of C.
  60.  
  61.     The specific Amiga implementation uses file descriptors (see
  62.     the file_descriptor manual page) as its interface to the
  63.     filesystem.
  64.  
  65.     Remember that a stdio file pointer is NOT a file descriptor nor
  66.     an AmigaDOS file handle.  You may call only stdio routines (fopen,
  67.     fclose, fread, fwrite, etc...) with file pointers.
  68.  
  69.     Some C implementations flush stdout whenever stdin is read.  DICE
  70.     does not do this.
  71.  
  72.  
  73.  
  74. stdio/clearerr                        stdio/clearerr
  75.  
  76.    NAME
  77.     clearerr - clear error associated with a file pointer
  78.  
  79.    SYNOPSIS
  80.     #include <stdio.h>
  81.  
  82.     void clearerr(fp);              (MACRO)
  83.     FILE *fp;
  84.  
  85.    FUNCTION
  86.     The clearerr() macro clears both the EOF flag and the ERROR
  87.     flag associated with a file pointer.  When an ERROR occurs on
  88.     a file pointer further fread, fwrite, and some other calls will
  89.     not work (i.e. fail) until the ERROR indicator is cleared.
  90.  
  91.    NOTE
  92.     refer to the file_pointer manual page for general information
  93.  
  94.    INPUTS
  95.     FILE *fp;    file pointer to clear the error on.
  96.  
  97.    RESULTS
  98.     none,    the error and EOF indicators are cleared
  99.  
  100.    SEE ALSO
  101.     feof, ferror, rewind, fseek
  102.  
  103.  
  104. stdio/fclose                        stdio/fclose
  105.  
  106.    NAME
  107.     fclose - close a file pointer
  108.  
  109.    SYNOPSIS
  110.     #include <stdio.h>
  111.  
  112.     int error = fclose(fp);
  113.     FILE *fp;
  114.  
  115.    FUNCTION
  116.     fclose flushes any data remaining in the file pointer's
  117.     output buffer to the file and then closes the file.  The
  118.     file pointer is no longer valid.
  119.  
  120.     fclose returns any error condition that occured while flushing
  121.     the buffered data to the file.    The file is still closed even
  122.     if an error occurs.
  123.  
  124.    NOTE
  125.     You can fclose(stdin), fclose(stdout), and fclose(stderr) as
  126.     you wish to save space and/or detach your process from the
  127.     console (i.e. allow the console window to be closed).
  128.  
  129.    WARNING
  130.     If you fclose stdin, stdout, and stderr with the intension of
  131.     removing all references to the console window there is still
  132.     one more thing you have to do, and that is put a NULL in
  133.     your processes pr_ConsoleTask field.  Otherwise, while the
  134.     console window will be able to close, your process will still
  135.     have a reference to the now non existant window if it attempts
  136.     to spawn or Execute() other processes.
  137.  
  138.     refer to the file_pointer manual page for general information
  139.  
  140.    INPUTS
  141.     FILE *fp;    file pointer
  142.  
  143.    RESULTS
  144.     int error;    error on fclose, or 0 if none
  145.  
  146.    SEE ALSO
  147.     fopen, fread, fwrite, fgets, fputs
  148.  
  149.  
  150. stdio/fdopen                        stdio/fdopen
  151.  
  152.    NAME
  153.     fdopen - associate a file pointer with an already open file
  154.          descriptor
  155.  
  156.    SYNOPSIS
  157.     #include <stdio.h>
  158.  
  159.     FILE *fp = fdopen(fd, modes);
  160.     int fd;
  161.     char *modes;
  162.  
  163.    FUNCTION
  164.     fdopen associates an already open file descriptor with a file
  165.     pointer.  Note that fclose()ing the file pointer will also
  166.     close() the file descriptor.
  167.  
  168.     Refer to the fopen manual page for a description of available
  169.     modes.    Note that when you use fdopen the file will not be
  170.     truncated and if you specify mode 'a' for append, the file
  171.     descriptor MUST have been open()'d with the O_APPEND flag.
  172.  
  173.     That is, the mode string should be similar to the open flags
  174.     that were used to open the file descriptor.
  175.  
  176.    NOTE
  177.     refer to the file_pointer manual page for general information
  178.  
  179.    INPUTS
  180.     int fd;     file descriptor to associated with a new file pointer
  181.     char *modes;    modes string, such as "r+".
  182.  
  183.    RESULTS
  184.     FILE *fp;    new file pointer or NULL if an error occured
  185.  
  186.    SEE ALSO
  187.     fopen, fread, fwrite, fgets, fputs
  188.  
  189.  
  190. stdio/feof                        stdio/feof
  191.  
  192.    NAME
  193.     feof   - return EOF condition for file pointer
  194.  
  195.    SYNOPSIS
  196.     #include <stdio.h>
  197.  
  198.     int r = feof(fp);                   (MACRO)
  199.     FILE *fp;
  200.  
  201.    FUNCTION
  202.     feof returns the EOF status of a file pointer.    The status is
  203.     not changed by this macro.  0 is returned if no EOF condition
  204.     exists, non-zero if an EOF condition exists (NOT necessarily
  205.     1 or -1, just non-zero).
  206.  
  207.     use clearerr() to clear the EOF condition.  Also, fseek() and
  208.     rewind() also clear an EOF condition.
  209.  
  210.    NOTE
  211.     refer to the file_pointer manual page for general information
  212.  
  213.    INPUTS
  214.     FILE *fp;    file pointer
  215.  
  216.    RESULTS
  217.     int r;        0 if no EOF condition exists, != 0 if an EOF
  218.             condition exists (not necessarily 1 or -1).
  219.  
  220.    SEE ALSO
  221.     fopen, fclose, fread, fwrite, fgets, fputs
  222.  
  223.  
  224. stdio/ferror                        stdio/ferror
  225.  
  226.    NAME
  227.     ferror - return ERROR condition for file pointer
  228.  
  229.    SYNOPSIS
  230.     #include <stdio.h>
  231.  
  232.     int r = ferror(fp);                 (MACRO)
  233.     FILE *fp;
  234.  
  235.    FUNCTION
  236.     ferror returns the ERROR status of a file pointer.  The status is
  237.     not changed by this macro.  0 is returned if no ERROR condition
  238.     exists, non-zero if an ERROR condition exists (NOT necessarily 1 or
  239.     -1, just non-zero).
  240.  
  241.    NOTE
  242.     refer to the file_pointer manual page for general information
  243.  
  244.    INPUTS
  245.     FILE *fp;    file pointer
  246.  
  247.    RESULTS
  248.     int r;        0 if no ERROR condition exists, != 0 if an ERROR
  249.             condition exists (not necessarily 1 or -1).
  250.  
  251.    SEE ALSO
  252.     fopen, fclose, fread, fwrite, fgets, fputs
  253.  
  254.  
  255. stdio/fflush                        stdio/fflush
  256.  
  257.    NAME
  258.     fflush - flush buffers to file
  259.  
  260.    SYNOPSIS
  261.     #include <stdio.h>
  262.  
  263.     int error = fflush(fp);
  264.     FILE *fp;
  265.  
  266.    FUNCTION
  267.     fflush writes out any buffered data out to the file descriptor
  268.     associated with the file pointer.
  269.  
  270.     Normally a file is either unbuffered, line buffered, or fully
  271.     buffered.  fflush is useful in the later two cases as is shown
  272.     by the example.
  273.  
  274.     fflush will return -1 if a write error occured, 0 if no error
  275.     occured.
  276.  
  277.    NOTE
  278.     refer to the file_pointer manual page for general information
  279.  
  280.    EXAMPLE
  281.     /*
  282.      *  Since text to stdout is normally line buffered, if we do not
  283.      *  write out a newline '\n' then the line is still buffered in
  284.      *  memory and we have to fflush() to write it out.
  285.      */
  286.  
  287.     #include <stdio.h>
  288.  
  289.     main()
  290.     {
  291.         char buf[256];
  292.  
  293.         printf("Enter a number -");
  294.         fflush(stdout);
  295.         gets(buf);
  296.         printf("Munch Munch...");
  297.         fflush(stdout);
  298.         sleep(1);
  299.         puts("Thanks!");
  300.     }
  301.  
  302.    INPUTS
  303.     FILE *fp;    file pointer
  304.  
  305.    RESULTS
  306.     int error;    0 if no error, -1 on error.
  307.  
  308.    SEE ALSO
  309.     fopen, fclose, fread, fwrite, fgets, fputs
  310.  
  311.  
  312. stdio/fgetc                        stdio/fgetc
  313. stdio/getc                        stdio/getc
  314.  
  315.    NAME
  316.     fgetc - get a single character from a file pointer
  317.     getc  - get a single character from a file pointer (MACRO)
  318.  
  319.    SYNOPSIS
  320.     #include <stdio.h>
  321.  
  322.     int c = fgetc(fp);
  323.     int c = getc(fp);                   (MACRO)
  324.     FILE *fp;
  325.  
  326.    FUNCTION
  327.     [f]getc() reads a single character from a file pointer.  The value
  328.     returned is actually an int because EOF (-1) must be differentiated
  329.     from a 255.
  330.  
  331.     [f]getc() returns an integer 0-255 or EOF (-1) if an end of file
  332.     occurs.
  333.  
  334.    NOTE
  335.     refer to the file_pointer manual page for general information
  336.  
  337.    EXAMPLE
  338.     /*
  339.      *  copy stdin to stdout using getc/putc.  Normally one uses
  340.      *  fread/fwrite, but I'll save that for the fread manual page.
  341.      *
  342.      *  note that I output the initial message to stderr so it does
  343.      *  not get stuck into stdout in case the user has redirected
  344.      *  stdout.
  345.      */
  346.  
  347.     #include <stdio.h>
  348.  
  349.     main()
  350.     {
  351.         int c;
  352.  
  353.         fputs("Type a couple of lines, then ^\ (EOF)\n", stderr);
  354.         while ((c = getc(stdin)) != EOF) {
  355.         putc(c, stdout);
  356.         }
  357.         return(0);
  358.     }
  359.  
  360.    INPUTS
  361.     FILE *fp;    file pointer
  362.  
  363.    RESULTS
  364.     int c;        character 0 to 255, or EOF (-1).
  365.  
  366.    SEE ALSO
  367.     putc, fputc, fread, fwrite
  368.  
  369.  
  370. stdio/fgetpos                        stdio/fgetpos
  371.  
  372.    NAME
  373.     fgetpos - get current file position
  374.  
  375.    SYNOPSIS
  376.     #include <stdio.h>
  377.  
  378.     int error = fgetpos(fp, &pos);
  379.     fpos_t pos;
  380.  
  381.    FUNCTION
  382.     fgetpos() returns the current seek position and is roughly equivalent
  383.     to ftell().  fgetpos() is a new ANSI call to better support C
  384.     compilers that use 16 bit integers.  DICE uses 32 bit integers so
  385.     fgetpos() is not so useful.
  386.  
  387.     fgetpos() takes a file pointer and the address of a fpos_t type
  388.     (a long).  It fills the fpos_t variable with the current file
  389.     position and returns 0 if all went well, non-zero if an error
  390.     occured.
  391.  
  392.    NOTE
  393.     refer to the file_pointer manual page for general information
  394.  
  395.    EXAMPLE
  396.     /*
  397.      *  return the length of the file specified on the command line.
  398.      *  P.S. it is more efficient to use open/lseek/close instead
  399.      *  of fopen/fseek/fgetpos/fclose
  400.      */
  401.  
  402.     #include <stdio.h>
  403.  
  404.     main(ac, av)
  405.     int ac;
  406.     char **av;
  407.     {
  408.         FILE *fp;
  409.         fpos_t off;
  410.  
  411.         if (ac == 1) {
  412.         puts("Expected a filename argument");
  413.         exit(1);
  414.         }
  415.         fp = fopen(av[1], "r");
  416.         if (fp == NULL) {
  417.         printf("Unable to open %s\n", av[1]);
  418.         exit(10);
  419.         }
  420.         fseek(fp, 0L, SEEK_END);
  421.         if (fgetpos(fp, &off)) {
  422.         puts("Error getting file position");
  423.         exit(20);
  424.         }
  425.         fclose(fp);
  426.         printf("File %s is %d bytes\n", av[1], off);
  427.         return(0);
  428.     }
  429.  
  430.    INPUTS
  431.     FILE *fp;    file pointer
  432.  
  433.     fpos_t *pos;    pointer to an fpos_t type that the position is
  434.             loaded into.
  435.  
  436.    RESULTS
  437.     int error;    0 if no error, non-zero on error
  438.  
  439.    SEE ALSO
  440.     ftell, rewind, fseek, rewind
  441.  
  442.  
  443. stdio/fgets                        stdio/fgets
  444.  
  445.    NAME
  446.     fgets - get a line from a file pointer
  447.  
  448.    SYNOPSIS
  449.     #include <stdio.h>
  450.  
  451.     char *ptr = fgets(buf, maxlen, fp);
  452.     char *buf;
  453.     int maxlen;
  454.     FILE *fp;
  455.  
  456.    FUNCTION
  457.     fgets() gets a line from the specified file pointer, returning
  458.     the first argument (buf) or NULL if an error or EOF occurs.
  459.  
  460.     fgets() stores the line in buf, up to maxlen characters.  This
  461.     maximum includes a terminating newline '\n' and nul '\0'.
  462.  
  463.     It is common to get confused between gets(), fgets(), puts(), and
  464.     fputs().  gets() strips off any newline '\n' and puts() adds one
  465.     while fgets() keeps the newline at the end of the line and fputs()
  466.     does NOT add one.   gets() and puts() work on stdin and stdout
  467.     while fgets() and fputs() work on arbitrary file pointers.
  468.  
  469.     If more than maxlen - 1 characters are in the line fgets will
  470.     terminate operation and put a nul as the last character (so the
  471.     buffer is still a valid string).
  472.  
  473.    NOTE
  474.     refer to the file_pointer manual page for general information
  475.  
  476.    EXAMPLE
  477.     #include <stdio.h>
  478.  
  479.     main()
  480.     {
  481.         unsigned char buf[128];
  482.         short i;
  483.  
  484.         printf("Enter a line - ");
  485.         fflush(stdout);
  486.         if (fgets(buf, sizeof(buf), stdin) == NULL)
  487.         exit(1);
  488.  
  489.         printf("In Hex: ");
  490.         for (i = 0; buf[i]; ++i)
  491.         printf(" %02x", buf[i]);
  492.         puts("");
  493.         return(0);
  494.     }
  495.  
  496.    INPUTS
  497.     char *buf;    buffer
  498.     int maxlen;    maximum buffer size
  499.     FILE *fp;    file pointer
  500.  
  501.    RESULTS
  502.     char *ptr;    buf if all is well, or NULL if error or EOF
  503.  
  504.    SEE ALSO
  505.     gets, puts, fputs, fread, getc, fgetc
  506.  
  507.  
  508. stdio/fileno                        stdio/fileno
  509.  
  510.    NAME
  511.     fileno - return file descriptor given a file pointer
  512.  
  513.    SYNOPSIS
  514.     #include <stdio.h>
  515.  
  516.     int fd = fileno(fp);                (MACRO)
  517.     FILE *fp;
  518.  
  519.    FUNCTION
  520.     The fileno() macro returns the file descriptor (open, close, read,
  521.     write) associated with the file pointer (fopen, fclose, fread,
  522.     fwrite).
  523.  
  524.     This is still not the AmigaDOS file handle... to get that you must
  525.     use the fdtofh() call.
  526.  
  527.    WARNING
  528.     If you use the file descriptor of a file pointer the file pointer
  529.     will get its seek position confused.  Additionally, there might
  530.     be unflushed data in the file pointer's buffers that has not
  531.     been written out to the file descriptor yet.  There also might
  532.     be unread input on the file pointer's input buffers already
  533.     read from the file descriptor.
  534.  
  535.    NOTE
  536.     refer to the file_pointer manual page for general information
  537.  
  538.    EXAMPLE
  539.     /*
  540.      *  stdin defaults to file descriptor 0
  541.      *  stdout defaults to file descriptor 1
  542.      *  stderr defaults to file descriptor 2
  543.      */
  544.  
  545.     #include <stdio.h>
  546.     #include <assert.h>
  547.  
  548.     main()
  549.     {
  550.         assert(fileno(stdin) == 0);
  551.         assert(fileno(stdout) == 1);
  552.         assert(fileno(stderr) == 2);
  553.         return(0);
  554.     }
  555.  
  556.    INPUTS
  557.     FILE *fp;    file pointer
  558.  
  559.    RESULTS
  560.     int fd;     associated file descriptor
  561.  
  562.    SEE ALSO
  563.     fdopen, fopen, fclose, open, close
  564.  
  565.  
  566. stdio/fopen                        stdio/fopen
  567.  
  568.    NAME
  569.     fopen - open a file and create a file pointer for it
  570.  
  571.    SYNOPSIS
  572.     #include <stdio.h>
  573.  
  574.     FILE *fp = fopen(filename, modes)
  575.     char *filename;
  576.     char *modes;
  577.  
  578.    FUNCTION
  579.     fopen is the grand master of stdio; It opens and possibly creates a
  580.     file and returns a new file pointer for use by the program.
  581.  
  582.     The first argument is the file to open, the second is a string
  583.     containing one or mode characters defined as follows:
  584.  
  585.     r   open for reading, the file must already exist
  586.  
  587.     w   open for writing, the file is created if it does not exist,
  588.         truncated if it does
  589.  
  590.     a   open for append, writes always append to the file.    If 'a' is
  591.         ever specified, the file starts out positioned at the end
  592.         instead of at the beginning.  This mode also creates the
  593.         file but only if it does not already exist.
  594.  
  595.     +   along with 'r' this also allows writing to the file
  596.         along with 'w' this also allows reading from the file
  597.  
  598.     b   open for binary read/write, else the file is assumed to contain
  599.         text (this is ignored by DICE since there is no difference on
  600.         the Amiga).
  601.  
  602.     All combinations except "rw" are allowed.  One uses "r+" or "w+"
  603.     instead of "rw".  By the above description "r+" is used to update
  604.     an existing file while "w+" is used to create a new file and then
  605.     allow reads as well as writes to it.
  606.  
  607.     "wa" is equivalent to creating a new file and then appending to
  608.     it.  "r+a" is equivalent to appending to an already existing
  609.     file.
  610.  
  611.     Other examples of valid modes combinations: "r+b", "w+b", "rb", "wb",
  612.     "ab", "w", "r", "r+", "a", etc...
  613.  
  614.    NOTE
  615.     refer to the file_pointer manual page for general information
  616.  
  617.    EXAMPLE
  618.     /*
  619.      *  create a new file and write some text to it
  620.      */
  621.  
  622.     #include <stdio.h>
  623.     #include <assert.h>
  624.  
  625.     main()
  626.     {
  627.         FILE *fp = fopen("T:xx", "w");
  628.         char buf[256];
  629.  
  630.         assert(fp);
  631.  
  632.         puts("Enter a line");
  633.         if (fgets(buf, sizeof(buf), stdin)) {
  634.         fputs(buf, fp);
  635.         puts("The line has been written to T:xx");
  636.         }
  637.         fclose(fp);
  638.  
  639.         return(0);
  640.     }
  641.  
  642.    INPUTS
  643.     char *filename;     file name to open
  644.     char *modes;        open modes string
  645.  
  646.    RESULTS
  647.     FILE *fp;        new file pointer
  648.  
  649.    SEE ALSO
  650.     fdopen, fopen, fclose, open, close
  651.  
  652.  
  653. stdio/printf                        stdio/printf
  654. stdio/fprintf                        stdio/fprintf
  655. stdio/sprintf                        stdio/sprintf
  656. stdio/vprintf                        stdio/vprintf
  657. stdio/vfprintf                        stdio/vfprintf
  658. stdio/vsprintf                        stdio/vsprintf
  659.  
  660.    NAME
  661.     printf - formatted output to stdout, file pointer, or buffer
  662.  
  663.    SYNOPSIS
  664.     #include <stdio.h>
  665.     #include <stdarg.h>    /*  v[f/s]printf() only */
  666.  
  667.     int n = printf(fmt, ...);
  668.     int n = fprintf(fp, fmt, ...);
  669.     int n = sprintf(buf, fmt, ...);
  670.     int n = vprintf(fmt, argvect);
  671.     int n = vfprintf(fp, fmt, argvect);
  672.     int n = vsprintf(buf, fmt, argvect);
  673.  
  674.     FILE *fp;
  675.     char *fmt;
  676.     char *buf;
  677.     va_list argvect;
  678.  
  679.    FUNCTION
  680.     These various connotations offer formatted printing.  printf and
  681.     vprintf output to stdout; fprintf and vfprintf output to a
  682.     file pointer (fp); sprintf and vsprintf output to a character
  683.     buffer.
  684.  
  685.     All routines return the number of characters written if successful,
  686.     a negative number if not.  Only sprintf and vsprintf is limited
  687.     in terms of output size (it cannot exceed the buffer you give it).
  688.  
  689.     The common argument to all routines is the format specifier.  The
  690.     format specifier is scanned to determine how to handle the arguments
  691.     to the call (or the arglist for v*printf connotations).  Characters
  692.     are copied to the output until a % is encountered.  %% indicates a
  693.     literal '%' character.  Otherwise, the % is followed by a control
  694.     sequence that tells printf how to output an argument quantity.    The
  695.     quantity is output and the scan continues until the end of the
  696.     format string.
  697.  
  698.     The % format is as follows:
  699.  
  700.         %[flags][#[.#]][modifier]<conversion-specifier>
  701.  
  702.     Items in brackets are option.  After the % zero or more flags may
  703.     be specified.  Then, an optional integer which represents the
  704.     minimum field width for the object.  If an integer is specified
  705.     it may be followed by a period and another integer that represents
  706.     that precision with which a number is printed.    Zero or more
  707.     modifiers may then be specified followed by a mandatory conversion
  708.     specifier.
  709.  
  710.     Either or both integers (#[.#]) may be specified as a '*', as in
  711.     "%*d", specifying that the minimum field width and/or precision
  712.     is specified as an integer in the argument that occurs before
  713.     the conversion object.    For example, printf("x%*dx\n", 10, 23);
  714.     would print the number 23 right justified in a field 10 characters
  715.     wide.
  716.  
  717.     FLAGS:
  718.     -     left justify text within its field, otherwise output is right
  719.           justified
  720.  
  721.     +     precede a signed number with a plus sign if it is positive
  722.           (negative numbers are always preceeded with a minus sign)
  723.  
  724.       <space> precede a positive signed number with a space so the number's
  725.           width matches that of itself if it were negative.
  726.  
  727.     #     forces numeric data items to be formatted such that their type
  728.           is known.  The following effects occur given a conversion
  729.           specifier:
  730.  
  731.             e, E, f, F        always retains decimal point
  732.  
  733.             g, G        always retains decimal point
  734.                     and trailing zeros are kept
  735.  
  736.             x, X        prints '0x' and '0X' respectively
  737.                     before the number
  738.  
  739.           (current not implemented by DICE)
  740.  
  741.     0     pad with zeros instead of spaces.  Ignored if a precision
  742.           is specified or if the '-' flag is specified.
  743.  
  744.           (currently partially implemented by DICE)
  745.  
  746.     MODIFIERS
  747.  
  748.     h     Indicates the corresponding integer argument is a short or
  749.           an unsigned short.
  750.  
  751.           under DICE, this has no effect since integers are 32 bits
  752.  
  753.     l     Indicates the corresponding integer argument is a long or
  754.           unsigned long.  Indicates floating point argument is a
  755.           double (else is a float)
  756.  
  757.           under DICE, for integers, this is superfluous, but for
  758.           portability reasons you want to specify it when an argument
  759.           is explicitly a long.
  760.  
  761.     L     Indicates the corresponding floating point argument is a
  762.           long double (16 byte quantity)  (currently not implemented
  763.           by DICE)
  764.  
  765.     CONVRSION SPECIFIER
  766.  
  767.     c     Output the character represented by the integer quantity
  768.  
  769.     d     Output a signed integer
  770.  
  771.     e     Output a double quantity in exponential form, the format:
  772.           The precision specifies the number of digits beyond the
  773.           decimal point to print
  774.  
  775.             [-]d.dddddde+/-dd
  776.  
  777.     E     e conversion but use upper case E in exponent:  E+/-dd
  778.  
  779.     f     Output a double quantity in the form:  The precision specifies
  780.           the number of digits beyond the decimal point to print
  781.  
  782.             [-]d.dddddd
  783.  
  784.     g     Output a double quantity using either the 'e' or 'f' form,
  785.           depending on the exponent.
  786.  
  787.     G     Output a double quantity using either the 'E' or 'f' form,
  788.           depending on the exponent.
  789.  
  790.     i     same as 'd'
  791.  
  792.     n     The argument is a pointer to an integer which is used to
  793.           set the integer to the bytes written out so far.    This is
  794.           especially useful with sprintf to determine where a particular
  795.           part of the format begins in the output buffer.
  796.  
  797.     o     The unsigned integer quantity is converted to ascii-octal
  798.  
  799.     p     The pointer is printed (basically the address is printed)
  800.  
  801.     s     The string represented by the character pointer is printed
  802.  
  803.     u     The unsigned integer quantity is converted to ascii-decimal
  804.  
  805.     x     The unsigned integer quantity is converted to ascii-hex using
  806.           '0'-'9', 'a'-'f'.
  807.  
  808.     X     The unsigned integer quantity is converted to ascii-hex using
  809.           upper case A-F instead of lower case.
  810.  
  811.    EXAMPLE
  812.     /*
  813.      *  Example use of most conversion specifiers.    Compile -lm to
  814.      *  get the math pfmt.
  815.      */
  816.  
  817.     #include <stdio.h>
  818.     #include <stdarg.h>
  819.  
  820.     void gagprint();
  821.  
  822.     main()
  823.     {
  824.         char buf[256];
  825.         int i;
  826.         int n;
  827.  
  828.         n = printf("ab%c %03d %le %lf %2.2lf %n%o %p %sXX %u %x %X %08lx\n",
  829.         'c',                /*  %c      -> 'c'      */
  830.         43,            /*    %03d    -> '043'    */
  831.         1.23E-2,
  832.         1.23E-2,
  833.         1.257,            /*    %2.2lf    -> 1.26     */
  834.         &i,
  835.         11,            /*    %o    -> '13'     */
  836.         buf,            /*    %p    -> <hex-ptr-addr>   */
  837.         "FuBar",
  838.         32094,            /*    %u    -> 32094    */
  839.         4095,            /*    %x            */
  840.         4095,            /*    %X            */
  841.         4095            /*    %08lx            */
  842.         );
  843.         printf("%d chars written\n", n);
  844.  
  845.         n = printf("%*s%s\n", i, "", "^Octal Number");
  846.         printf("%d chars written\n", n);
  847.  
  848.         n = sprintf(buf, "FuBar%s", "Bletch");
  849.         puts(buf);
  850.         printf("%d chars written\n", n);
  851.  
  852.         n = fprintf(stdout, "This is an fprintf\n");
  853.         printf("%d chars written\n", n);
  854.  
  855.         gagprint("%d %d %d\n", 1, 2, 3);
  856.         return(0);
  857.     }
  858.  
  859.     void
  860.     gagprint(ctl, ...)
  861.     char *ctl;
  862.     {
  863.         va_list va;
  864.         int n;
  865.  
  866.         va_start(va, ctl);
  867.         n = vprintf(ctl, va);
  868.         printf("%d chars written\n", n);
  869.         va_end(va);
  870.     }
  871.  
  872.    INPUTS
  873.     FILE *fp;        file pointer (fprintf, vfprintf)
  874.     char *fmt;        format string, e.g. "Answer is %d\n"
  875.     char *buf;        buffer (sprintf, vsprintf)
  876.     va_list argvect;    arg list (vprintf, vfprintf, vsprintf)
  877.  
  878.    RESULTS
  879.     int n;            number of characters written if successful,
  880.                 a negative number if not.  for sprintf and
  881.                 vsprintf the nul character at the end of the
  882.                 string is NOT included in the count.
  883.  
  884.    SEE ALSO
  885.     puts, fputs, fwrite
  886.  
  887.  
  888. stdio/fputc                        stdio/fputc
  889. stdio/putc                        stdio/putc
  890.  
  891.    NAME
  892.     fputc - write a single character to a file pointer
  893.     putc  - write a single character to a file pointer (MACRO)
  894.  
  895.    SYNOPSIS
  896.     #include <stdio.h>
  897.  
  898.     int c = fputc(c, fp);
  899.     int c = putc(c, fp);
  900.     FILE *fp;
  901.  
  902.    FUNCTION
  903.     [f]putc() writes a single character to a file pointer.  If all
  904.     goes well the character is returned, else EOF is returned.
  905.  
  906.     fputc() is a function call while putc() is a macro
  907.  
  908.    NOTE
  909.     refer to the file_pointer manual page for general information
  910.  
  911.    EXAMPLE
  912.     /*
  913.      *  copy stdin to stdout using fgetc/fputc.  Normally one uses
  914.      *  fread/fwrite, but I'll save that for the fread manual page.
  915.      *
  916.      *  note that I output the initial message to stderr so it does
  917.      *  not get stuck into stdout in case the user has redirected
  918.      *  stdout.
  919.      */
  920.  
  921.     #include <stdio.h>
  922.  
  923.     main()
  924.     {
  925.         int c;
  926.  
  927.         fputs("Type a couple of lines, then ^\ (EOF)\n", stderr);
  928.         while ((c = fgetc(stdin)) != EOF) {
  929.         fputc(c, stdout);
  930.         }
  931.         return(0);
  932.     }
  933.  
  934.    INPUTS
  935.     int c;        character to write
  936.     FILE *fp;    file pointer
  937.  
  938.    RESULTS
  939.     int c;        character written (same as first argument) or EOF
  940.             if error.
  941.  
  942.    SEE ALSO
  943.     getc, putc, fputc, fread, fwrite, puts, fputs, gets, fgets
  944.  
  945.  
  946. stdio/fputs                        stdio/fputs
  947. stdio/puts                        stdio/puts
  948.  
  949.    NAME
  950.     fputs - write a string to a file pointer
  951.     puts  - write a string to stdout and also write a newline
  952.  
  953.    SYNOPSIS
  954.     #include <stdio.h>
  955.  
  956.     int error = fputs(s, fp);
  957.     int error = puts(s);
  958.  
  959.     const char *s;
  960.     FILE *fp;
  961.  
  962.    FUNCTION
  963.     fputs writes a string to a file pointer all the way up to, but not
  964.     including, the nul.  puts does the same thing but to stdout, and
  965.     puts additionally writes a newline out.
  966.  
  967.    NOTE
  968.     refer to the file_pointer manual page for general information
  969.  
  970.     It is common to get confused between fputs and puts.  Remember that
  971.     puts adds a newline to the output while fputs does not.  gets strips
  972.     the newline from an input line while fgets does not.
  973.  
  974.    EXAMPLE
  975.  
  976.     #include <stdio.h>
  977.  
  978.     main()
  979.     {
  980.         fputs("This is a test of fputs\n", stdout); /* note newline    */
  981.         puts("This is a test of puts");             /*  note lack of   */
  982.         puts("That's it!");
  983.         return(0);
  984.     }
  985.  
  986.    INPUTS
  987.     char *s;    string to write
  988.     FILE *fp;    file pointer
  989.  
  990.    RESULTS
  991.     int error;    0 or positive if all went ok, else negative.  Note
  992.             that unlike *printf() routines the number of chars
  993.             written out is NOT returned.
  994.  
  995.    SEE ALSO
  996.     getc, putc, fputc, fread, fwrite, gets, fgets
  997.  
  998.  
  999. stdio/fread                        stdio/fread
  1000.  
  1001.    NAME
  1002.     fread - read data from a file pointer
  1003.  
  1004.    SYNOPSIS
  1005.     #include <stdio.h>
  1006.  
  1007.     size_t robjs = fread(buf, objsize, nobjs, fp);
  1008.     void *buf;
  1009.     size_t objsize;
  1010.     size_t nobjs;
  1011.     FILE *fp;
  1012.  
  1013.    FUNCTION
  1014.     fread() reads an arbitrary number of objects from a file pointer
  1015.     into the specified buffer and returns the actual number of objects
  1016.     read.
  1017.  
  1018.     If the return value robjs is not equal to nobjs then fread() was
  1019.     unable to read the requested number of objects due to either a
  1020.     read error or EOF condition.  If the file is already completely
  1021.     exhausted fread() simply returns 0.
  1022.  
  1023.     Having two size arguments, an object size and number of objects,
  1024.     simplifies the reading of structure arrays off disk.
  1025.  
  1026.    NOTE
  1027.     To use fread to read an arbitrary number of bytes one normally
  1028.     uses the form:    r = fread(buf, 1, n, fp); ... i.e. n objects
  1029.     of size 1.
  1030.  
  1031.     fread() will attempt to read objsize * nobjs bytes into the
  1032.     specified buffer.
  1033.  
  1034.    EXAMPLE
  1035.     /*
  1036.      *  NOTE:   run fwrite() example before running this example
  1037.      *        to create the dummy file.
  1038.      */
  1039.  
  1040.     #include <stdio.h>
  1041.  
  1042.     #define NOBJS    10
  1043.  
  1044.     typedef struct {
  1045.         short   a, b, c, d;
  1046.     } MyObj;
  1047.  
  1048.     main()
  1049.     {
  1050.         FILE *fp;
  1051.         static MyObj Obj[NOBJS];
  1052.  
  1053.         if (fp = fopen("T:fwrite_tmp", "rb")) {
  1054.         short n;
  1055.         while ((n = fread(Obj, sizeof(MyObj), NOBJS, fp)) > 0) {
  1056.             short i;
  1057.             for (i = 0; i < n; ++i) {
  1058.             printf("a = %-5d b = %-5d c = %-5d d = %-5d\n",
  1059.                 Obj[i].a, Obj[i].b, Obj[i].c, Obj[i].d
  1060.             );
  1061.             }
  1062.         }
  1063.         fclose(fp);
  1064.         } else {
  1065.         puts("Unable to open T:fwrite_tmp, run fwrite example first");
  1066.         exit(1);
  1067.         }
  1068.         return(0);
  1069.     }
  1070.  
  1071.    INPUTS
  1072.     void *buf;        buffer to load data into
  1073.     size_t objsize;     size of one object
  1074.     size_t nobjs;        number of objects to read
  1075.     FILE *fp;        file pointer to read objects from
  1076.  
  1077.    RESULTS
  1078.     size_t robjs;        number of objects actually read or 0 if EOF or
  1079.                 ERROR.
  1080.  
  1081.    SEE ALSO
  1082.     fwrite, fopen, fclose, fseek, ftell, rewind
  1083.  
  1084.  
  1085. stdio/freopen                        stdio/freopen
  1086.  
  1087.    NAME
  1088.     freopen - reopen a new file using an existing file pointer,
  1089.           the existing file is closed before it is reused.
  1090.  
  1091.    SYNOPSIS
  1092.     #include <stdio.h>
  1093.  
  1094.     FILE *fp = freopen(filename, modes, ofp)
  1095.     char *filename;
  1096.     char *modes;
  1097.     FILE *ofp;
  1098.  
  1099.    FUNCTION
  1100.     freopen works exactly like fopen but takes an additional argument...
  1101.     A file pointer to reuse.  This file pointer, ofp, must be reference
  1102.     a valid open file.  freopen() will close out ofp then reuse the
  1103.     descriptor to open the new file, returning ofp (fp == ofp) on
  1104.     success, NULL on failure.
  1105.  
  1106.     If the freopen fails NULL is returned and the original file
  1107.     pointer is still closed, but not free()d so you may call
  1108.     freopen again with the same ofp, even though it has already
  1109.     been closed.
  1110.  
  1111.     refer to the fopen() manual page for information on the modes
  1112.     string.
  1113.  
  1114.     freopen is often used to change a program's stdin, stdout, or
  1115.     stderr though to be frank, using a separate file pointer is
  1116.     normally much more modular.
  1117.  
  1118.    WARNING
  1119.     ANSI does not specify that the ofp can be used in a second freopen
  1120.     if the first freopen using ofp fails (returns NULL).  Many
  1121.     implementations free the file pointer.    This just might be
  1122.     the proper way of doing things but I dunno.  I suggest you do
  1123.     not use DICE's feature in that respect as I might have to
  1124.     change it back to free ofp if the new file is unopenable.
  1125.  
  1126.    NOTE
  1127.     refer to the file_pointer manual page for general information
  1128.  
  1129.    EXAMPLE
  1130.     /*
  1131.      *  re-open stdin to an Amiga console device
  1132.      */
  1133.  
  1134.     #include <stdio.h>
  1135.     #include <assert.h>
  1136.  
  1137.     main()
  1138.     {
  1139.         char buf[256];
  1140.  
  1141.         assert(freopen("CON:0/0/320/100/freopen-in", "r", stdin));
  1142.         assert(freopen("CON:320/0/320/100/freopen-out", "w", stdout));
  1143.  
  1144.         /*
  1145.          *    set to line buffered
  1146.          */
  1147.         setvbuf(stdin, NULL, _IOLBF, 0);
  1148.         setvbuf(stdout, NULL, _IOLBF, 0);
  1149.  
  1150.         puts("Type a line in the second window");
  1151.         gets(buf);
  1152.         fclose(stdin);
  1153.         fclose(stdout);
  1154.         fprintf(stderr, "Your line was: %s\n", buf);
  1155.  
  1156.         return(0);
  1157.     }
  1158.  
  1159.    INPUTS
  1160.     char *filename;     file name to open
  1161.     char *modes;        open modes string
  1162.     FILE *ofp;        open file pointer to reuse
  1163.  
  1164.    RESULTS
  1165.     FILE *fp;        same as ofp if the new open worked, NULL
  1166.                 otherwise
  1167.  
  1168.    SEE ALSO
  1169.     fdopen, fopen, fclose, open, close
  1170.  
  1171.  
  1172. stdio/fseek                        stdio/fseek
  1173.  
  1174.    NAME
  1175.     fseek - seek within a file pointer.
  1176.  
  1177.    SYNOPSIS
  1178.     #include <stdio.h>
  1179.  
  1180.     int error = fseek(fp, offset, how);
  1181.     FILE *fp;
  1182.     long offset;
  1183.     int how;
  1184.  
  1185.    FUNCTION
  1186.     fseek changes the current seek position within a file.    Offset is
  1187.     interpreted according to the how argument:
  1188.  
  1189.     how        offset
  1190.  
  1191.     SEEK_SET (0)    skip to position relative to beginning of file
  1192.     SEEK_CUR (1)    skip to position relative to current position in file
  1193.     SEEK_END (2)    skip to position relative to end of file
  1194.  
  1195.     So, for example, one may seek to the beginning of a file by
  1196.     fseek(fp, 0L, SEEK_SET);, to the end of the file by
  1197.     fseek(fp, 0L, SEEK_END); (i.e. calling getc() at this time would
  1198.     return an immediate EOF).  You can skip characters in a file
  1199.     with something like fseek(fp, 5L, SEEK_CUR); which skips 5 characters.
  1200.  
  1201.     Note that when seeking relative to the end of the file, negative
  1202.     offsets are used.  For example, to seek to the very last character
  1203.     in the file you would use fseek(fp, -1L, SEEK_END);
  1204.  
  1205.     fseek returns 0 on success, a negative number on ERROR.  A common
  1206.     mistake is to expect fseek to return the new position of the file
  1207.     but this is not what is returned.  Use ftell() or fgetpos() to
  1208.     determine the current offset into a file.
  1209.  
  1210.    NOTE
  1211.     refer to the file_pointer manual page for general information
  1212.  
  1213.     fseek flushes any buffered write data before seeking.
  1214.  
  1215.    EXAMPLE
  1216.     /*
  1217.      *  print a file backwards
  1218.      */
  1219.  
  1220.     #include <stdio.h>
  1221.  
  1222.     char Buf[4096];
  1223.  
  1224.     main(ac, av)
  1225.     int ac;
  1226.     char **av;
  1227.     {
  1228.         FILE *fp;
  1229.         long pos;
  1230.  
  1231.         if (ac == 1) {
  1232.         puts("Expected textfile argument");
  1233.         exit(1);
  1234.         }
  1235.         fp = fopen(av[1], "r");
  1236.         if (fp == NULL) {
  1237.         printf("Unable to open %s\n", av[1]);
  1238.         exit(1);
  1239.         }
  1240.         fseek(fp, 0L, SEEK_END);        /*  seek to end     */
  1241.         pos = ftell(fp);                /*  size of file    */
  1242.  
  1243.         while (pos > 0) {
  1244.         long bytes = ((pos > sizeof(Buf)) ? sizeof(Buf) : pos);
  1245.         long n;
  1246.  
  1247.         fseek(fp, pos - bytes, SEEK_SET);
  1248.         n = fread(Buf, 1, bytes, fp);
  1249.         if (n != bytes) {
  1250.             puts("read error");
  1251.             exit(1);
  1252.         }
  1253.         while (--n >= 0)        /*  dump buffer backwords to stdout */
  1254.             putc(Buf[n], stdout);
  1255.  
  1256.         pos -= bytes;
  1257.         }
  1258.         fclose(fp);
  1259.         return(0);
  1260.     }
  1261.  
  1262.    INPUTS
  1263.     FILE *fp;        file pointer to seek
  1264.     long offset;        offset relative to how
  1265.     int how;        0, 1, or 2 (absolute, relative, end-relative)
  1266.  
  1267.    RESULTS
  1268.     int error;
  1269.  
  1270.    SEE ALSO
  1271.     ftell, fgetpos, fsetpos, rewind
  1272.  
  1273.  
  1274. stdio/fsetpos                        stdio/fsetpos
  1275.  
  1276.    NAME
  1277.     fsetpos - set position within file pointer (nearly equivalent to
  1278.     fseek absolute)
  1279.  
  1280.    SYNOPSIS
  1281.     #include <stdio.h>
  1282.  
  1283.     int error = fsetpos(fp, &pos);
  1284.     FILE *fp;
  1285.     fpos_t pos;
  1286.  
  1287.    FUNCTION
  1288.     fsetpos() is a nearly useless call that is essentially the same
  1289.     as fseek(fp, (long)pos, 0);  fsetpos() seeks within a file pointer
  1290.     to the absolute position specified by an fpos_t type.  The
  1291.     address of an fpos_t object is passed to fsetpos().
  1292.  
  1293.     Normally one saves the current seek position into an fpos_t
  1294.     type using the fgetpos() function, then seeks back using
  1295.     the fsetpos() function.  In this way the programmer need not make
  1296.     any direct reference to the contents of the fpos_t type.
  1297.  
  1298.    EXAMPLE
  1299.     /*
  1300.      *  get a line, save current position, get rest of file, go back
  1301.      *  to saved position, retrieve line again and print again.
  1302.      */
  1303.  
  1304.     #include <stdio.h>
  1305.  
  1306.     main(ac, av)
  1307.     int ac;
  1308.     char **av;
  1309.     {
  1310.         FILE *fp;
  1311.         fpos_t save_pos;
  1312.         int count;
  1313.         char buf[256];
  1314.  
  1315.         if (ac == 1) {
  1316.         puts("Expected textfile argument");
  1317.         exit(1);
  1318.         }
  1319.         fp = fopen(av[1], "r");
  1320.         if (fp == NULL) {
  1321.         printf("Unable to open %s\n", av[1]);
  1322.         exit(1);
  1323.         }
  1324.         for (count = 0; fgets(buf, sizeof(buf), fp); ++count) {
  1325.         if (count == 0)             /*  just before second line */
  1326.             fgetpos(fp, &save_pos);
  1327.         fprintf(stdout, "%-3d: %s", count + 1, buf);
  1328.         }
  1329.         if (count < 2) {
  1330.         puts("not enough lines in file for example!");
  1331.         exit(1);
  1332.         }
  1333.         puts("--end of file, now seeking back to line 2--");
  1334.         fsetpos(fp, &save_pos);
  1335.         if (fgets(buf, sizeof(buf), fp) == NULL) {
  1336.         puts("error!");
  1337.         exit(1);
  1338.         }
  1339.         fprintf(stdout, "%-3d: %s", 2, buf);
  1340.         fclose(fp);
  1341.         return(0);
  1342.     }
  1343.  
  1344.    INPUTS
  1345.     FILE *fp;        file pointer to seek
  1346.     fpos_t *pos;        pointer to fpos_t type previously initialized
  1347.                 by a fgetpos() call.
  1348.  
  1349.    RESULTS
  1350.     int error;        0 if no error, < 0 if error
  1351.  
  1352.    SEE ALSO
  1353.     ftell, fsetpos, fseek, rewind
  1354.  
  1355.  
  1356. stdio/ftell                        stdio/ftell
  1357.  
  1358.    NAME
  1359.     ftell - return current position within file pointer
  1360.  
  1361.    SYNOPSIS
  1362.     #include <stdio.h>
  1363.  
  1364.     long pos = ftell(fp);
  1365.     FILE *fp;
  1366.  
  1367.    FUNCTION
  1368.     ftell() returns the current absolute seek offset within a file
  1369.     pointer.
  1370.  
  1371.    EXAMPLE
  1372.     /*
  1373.      *  get a line, save current position, get rest of file, go back
  1374.      *  to saved position, retrieve line again and print again.
  1375.      *
  1376.      *  like fsetpos() example but uses ftell()/fseek() instead
  1377.      */
  1378.  
  1379.     #include <stdio.h>
  1380.  
  1381.     main(ac, av)
  1382.     int ac;
  1383.     char **av;
  1384.     {
  1385.         FILE *fp;
  1386.         long save_pos;
  1387.         int count;
  1388.         char buf[256];
  1389.  
  1390.         if (ac == 1) {
  1391.         puts("Expected textfile argument");
  1392.         exit(1);
  1393.         }
  1394.         fp = fopen(av[1], "r");
  1395.         if (fp == NULL) {
  1396.         printf("Unable to open %s\n", av[1]);
  1397.         exit(1);
  1398.         }
  1399.         for (count = 0; fgets(buf, sizeof(buf), fp); ++count) {
  1400.         if (count == 0)             /*  just before second line */
  1401.             save_pos = ftell(fp);
  1402.         fprintf(stdout, "%-3d: %s", count + 1, buf);
  1403.         }
  1404.         if (count < 2) {
  1405.         puts("not enough lines in file for example!");
  1406.         exit(1);
  1407.         }
  1408.         puts("--end of file, now seeking back to line 2--");
  1409.         fseek(fp, save_pos, SEEK_SET);
  1410.         if (fgets(buf, sizeof(buf), fp) == NULL) {
  1411.         puts("error!");
  1412.         exit(1);
  1413.         }
  1414.         fprintf(stdout, "%-3d: %s", 2, buf);
  1415.         fclose(fp);
  1416.         return(0);
  1417.     }
  1418.  
  1419.    INPUTS
  1420.     FILE *fp;        file pointer retrieve seek position from
  1421.  
  1422.  
  1423.    RESULTS
  1424.     long pos;        current absolute seek position in file
  1425.  
  1426.    SEE ALSO
  1427.     ftell, fgetpos, fsetpos, fseek, rewind
  1428.  
  1429.  
  1430. stdio/fwrite                        stdio/fwrite
  1431.  
  1432.    NAME
  1433.     fwrite - write data to a file pointer
  1434.  
  1435.    SYNOPSIS
  1436.     #include <stdio.h>
  1437.  
  1438.     size_t robjs = fwrite(buf, objsize, nobjs, fp);
  1439.     const void *buf;
  1440.     size_t objsize;
  1441.     size_t nobjs;
  1442.     FILE *fp;
  1443.  
  1444.    FUNCTION
  1445.     fwrite() writes the specified number of objects to a file pointer
  1446.     from the specified buffer and returns the actual number of objects
  1447.     written or 0 or -1 depending on the error.
  1448.  
  1449.     If the return value robjs is not equal to nobjs then a write error
  1450.     occured.
  1451.  
  1452.     Having two size arguments, an object size and number of objects,
  1453.     simplifies the reading of structure arrays off disk.
  1454.  
  1455.    NOTE
  1456.     To use fwrite to read an arbitrary number of bytes one normally
  1457.     uses the form:    r = fwrite(buf, 1, n, fp); ... i.e. n objects
  1458.     of size 1.
  1459.  
  1460.    EXAMPLE
  1461.     /*
  1462.      *  NOTE:   run fread() example after this one to read data back
  1463.      *        from the file
  1464.      */
  1465.  
  1466.     #include <stdio.h>
  1467.  
  1468.     #define NOBJS    15
  1469.  
  1470.     typedef struct {
  1471.         short   a, b, c, d;
  1472.     } MyObj;
  1473.  
  1474.     main()
  1475.     {
  1476.         FILE *fp;
  1477.         MyObj O;
  1478.  
  1479.         if (fp = fopen("T:fwrite_tmp", "wb")) {
  1480.         short n;
  1481.         for (n = 0; n < NOBJS; ++n) {
  1482.             O.a = n;
  1483.             O.b = n * 2;
  1484.             O.c = n * 3;
  1485.             O.d = n * 4;
  1486.             if (fwrite(&O, sizeof(MyObj), 1, fp) != 1) {
  1487.             puts("write error");
  1488.             exit(1);
  1489.             }
  1490.         }
  1491.         fclose(fp);
  1492.         } else {
  1493.         puts("Unable to create T:fwrite_tmp");
  1494.         exit(1);
  1495.         }
  1496.         return(0);
  1497.     }
  1498.  
  1499.    INPUTS
  1500.     void *buf;        buffer to copy data from
  1501.     size_t objsize;     size of one object
  1502.     size_t nobjs;        number of objects to write
  1503.     FILE *fp;        file pointer to read objects from
  1504.  
  1505.    RESULTS
  1506.     size_t robjs;        number of objects actually written (0 or EOF on
  1507.                 error)
  1508.  
  1509.    SEE ALSO
  1510.     fread, fopen, fclose, fseek, ftell, rewind
  1511.  
  1512.  
  1513. stdio/getchar                        stdio/getchar
  1514.  
  1515.    NAME
  1516.     getchar - get character from stdin (MACRO)
  1517.  
  1518.    SYNOPSIS
  1519.     #include <stdio.h>
  1520.  
  1521.     int c = getchar();
  1522.  
  1523.    FUNCTION
  1524.     getchar() returns the next available character on stdin or EOF if
  1525.     no more characters are available.  getchar() is equivalent to
  1526.     getc(stdin).
  1527.  
  1528.    NOTE
  1529.     refer to the file_pointer manual page for general information
  1530.  
  1531.    EXAMPLE
  1532.     /*
  1533.      *  copy stdin to stdout using getchar/putchar.  Normally one uses
  1534.      *  fread/fwrite, but I'll save that for the fread manual page.
  1535.      *
  1536.      *  note that I output the initial message to stderr so it does
  1537.      *  not get stuck into stdout in case the user has redirected
  1538.      *  stdout.
  1539.      *
  1540.      *  See getc manual page for equivalent example using getc/putc
  1541.      */
  1542.  
  1543.     #include <stdio.h>
  1544.  
  1545.     main()
  1546.     {
  1547.         int c;
  1548.  
  1549.         fputs("Type a couple of lines, then ^\ (EOF)\n", stderr);
  1550.         while ((c = getchar()) != EOF) {
  1551.         putchar(c);
  1552.         }
  1553.         return(0);
  1554.     }
  1555.  
  1556.    INPUTS
  1557.     none
  1558.  
  1559.    RESULTS
  1560.     int c;        character 0 to 255, or EOF (-1) returned from stdin
  1561.  
  1562.    SEE ALSO
  1563.     putc, putchar, fputc, fread, fwrite, getc
  1564.  
  1565.  
  1566. stdio/gets                        stdio/gets
  1567.  
  1568.    NAME
  1569.     gets - get a line from stdin
  1570.  
  1571.    SYNOPSIS
  1572.     #include <stdio.h>
  1573.  
  1574.     char *ptr = gets(buf);
  1575.     char *buf;
  1576.  
  1577.    FUNCTION
  1578.     gets() gets a line from stdin returning its first argument (buf)
  1579.     if all went well, NULL if an error or EOF occurs.
  1580.  
  1581.     gets() stores the line into the specified buffer up to a maximum
  1582.     of 256 characters (includes \0).
  1583.  
  1584.     It is common to get confused between gets(), fgets(), puts(), and
  1585.     fputs().  gets() strips off any newline '\n' and puts() adds one
  1586.     while fgets() keeps the newline at the end of the line and fputs()
  1587.     does NOT add one.   gets() and puts() work on stdin and stdout
  1588.     while fgets() and fputs() work on arbitrary file pointers.
  1589.  
  1590.    NOTE
  1591.     refer to the file_pointer manual page for general information
  1592.  
  1593.    EXAMPLE
  1594.     #include <stdio.h>
  1595.  
  1596.     main()
  1597.     {
  1598.         char buf[256];
  1599.  
  1600.         printf("Enter a line - ");
  1601.         fflush(stdout);
  1602.         if (gets(buf) == NULL)
  1603.         exit(1);
  1604.         printf("Your line was: %s\n", buf);
  1605.         return(0);
  1606.     }
  1607.  
  1608.    INPUTS
  1609.     char *buf;    buffer, must be able to hold 256 characters.
  1610.  
  1611.    RESULTS
  1612.     char *ptr;    buf if all is well, or NULL if error or EOF
  1613.  
  1614.    SEE ALSO
  1615.     gets, puts, fputs, fread, getc, fgetc
  1616.  
  1617.  
  1618. stdio/perror                        stdio/perror
  1619.  
  1620.    NAME
  1621.     perror - output error message associated with errno and text
  1622.          to stderr.
  1623.  
  1624.    SYNOPSIS
  1625.     #include <stdio.h>
  1626.  
  1627.     void perror(str);
  1628.     const char *str;
  1629.  
  1630.    FUNCTION
  1631.     perror outputs the specified string, a colon, and the error number
  1632.     and error message associated with the current value of errno to
  1633.     stderr, ending with a newline.    perror is a common way to generate
  1634.     error messages due to IO failures.
  1635.  
  1636.    EXAMPLE
  1637.     #include <stdio.h>
  1638.  
  1639.     main()
  1640.     {
  1641.         FILE *fp = fopen("T:DoesNotExist", "r");
  1642.  
  1643.         if (fp) {
  1644.         puts("T:DoesNotExist isn't supposed to exist!");
  1645.         exit(1);
  1646.         }
  1647.         perror("fopen");
  1648.         return(0);
  1649.     }
  1650.  
  1651.    INPUTS
  1652.     char *str;    string message to include in error output
  1653.  
  1654.    RESULTS
  1655.     none
  1656.  
  1657.    SEE ALSO
  1658.  
  1659.  
  1660. stdio/putchar                        stdio/putchar
  1661.  
  1662.    NAME
  1663.     putchar - output character to stdout (MACRO)
  1664.  
  1665.    SYNOPSIS
  1666.     #include <stdio.h>
  1667.  
  1668.     int r = putchar(c);
  1669.  
  1670.    FUNCTION
  1671.     putchar() outputs a character to stdout, returning the output
  1672.     character unless an error occured.  If an error occured then
  1673.     EOF is returned.
  1674.  
  1675.    NOTE
  1676.     refer to the file_pointer manual page for general information
  1677.  
  1678.    EXAMPLE
  1679.     /*
  1680.      *  copy stdin to stdout using getchar/putchar.  Normally one uses
  1681.      *  fread/fwrite, but I'll save that for the fread manual page.
  1682.      *
  1683.      *  note that I output the initial message to stderr so it does
  1684.      *  not get stuck into stdout in case the user has redirected
  1685.      *  stdout.
  1686.      *
  1687.      *  See getc manual page for equivalent example using getc/putc
  1688.      */
  1689.  
  1690.     #include <stdio.h>
  1691.  
  1692.     main()
  1693.     {
  1694.         int c;
  1695.  
  1696.         fputs("Type a couple of lines, then ^\ (EOF)\n", stderr);
  1697.         while ((c = getchar()) != EOF) {
  1698.         putchar(c);
  1699.         }
  1700.         return(0);
  1701.     }
  1702.  
  1703.    INPUTS
  1704.     int c;        character to output, 0 to 255
  1705.  
  1706.    RESULTS
  1707.     int r;        same as c unless error occured in which case EOF.
  1708.  
  1709.    SEE ALSO
  1710.     putc, fputc, fread, fwrite, getc, getchar
  1711.  
  1712.  
  1713. stdio/remove                        stdio/remove
  1714.  
  1715.    NAME
  1716.     remove - delete a file
  1717.  
  1718.    SYNOPSIS
  1719.     #include <stdio.h>
  1720.  
  1721.     int error = remove(filename);
  1722.     const char *filename;
  1723.  
  1724.    FUNCTION
  1725.     remove() deletes the specified file path returning 0 on success,
  1726.     a negative number on failure.
  1727.  
  1728.     On the Amiga, an error will occur if you try to delete a file
  1729.     currently openned by yourself or any other process.
  1730.  
  1731.     remove() is an ANSI function.  unlink() does the same thing but
  1732.     is a UNIX compatible function.
  1733.  
  1734.    EXAMPLE
  1735.     /*
  1736.      *  delete the file 'T:xxx'
  1737.      */
  1738.  
  1739.     #include <stdio.h>
  1740.  
  1741.     main()
  1742.     {
  1743.         int error = remove("T:XXX");
  1744.  
  1745.         if (error < 0) {
  1746.         perror("remove(\"T:XXX\") failed");
  1747.         exit(1);
  1748.         }
  1749.         puts("T:XXX has been deleted");
  1750.         return(0);
  1751.     }
  1752.  
  1753.    INPUTS
  1754.     char *filename;     filename to delete
  1755.  
  1756.    RESULTS
  1757.     int error;        0 on success, a negative number on failure
  1758.  
  1759.    SEE ALSO
  1760.     unlink
  1761.  
  1762.  
  1763. stdio/rename                        stdio/rename
  1764.  
  1765.    NAME
  1766.     rename - rename a file, also is able to move a file from one
  1767.          directory to another on the same filesystem.
  1768.  
  1769.    SYNOPSIS
  1770.     #include <stdio.h>
  1771.  
  1772.     int error = rename(origname, newname);
  1773.     const char *origname;
  1774.     const char *newname;
  1775.  
  1776.    FUNCTION
  1777.     rename() renames a file.  You may also use rename() to move a file
  1778.     (& rename at the same time) to another directory on the same
  1779.     filesystem.
  1780.  
  1781.     rename returns 0 on success, a negative number on failure.
  1782.  
  1783.    EXAMPLE
  1784.     /*
  1785.      *  create the file T:xxjunk and the directory T:junkdir then
  1786.      *  move T:xxjunk into T:junkdir and rename to T:yyjunk at the
  1787.      *  same time.
  1788.      *
  1789.      *  As is aptly demonstrated by this example, some errors are not
  1790.      *  really errors.  For example, mkdir where the dir already exists
  1791.      *  is not usually an error.
  1792.      */
  1793.  
  1794.     #include <stdio.h>
  1795.     #include <assert.h>
  1796.     #include <errno.h>
  1797.  
  1798.     main()
  1799.     {
  1800.         FILE *fp;
  1801.         int error;
  1802.  
  1803.         error = mkdir("T:junkdir");
  1804.         if (error < 0 && errno != EEXISTS)
  1805.         perror("mkdir");
  1806.         fp = fopen("T:xxjunk", "w");
  1807.         if (fp == NULL) {
  1808.         perror("fopen");
  1809.         exit(1);
  1810.         }
  1811.         fprintf(fp, "This file was originally T:xxjunk!\n");
  1812.         fclose(fp);
  1813.  
  1814.         /*
  1815.          * now rename
  1816.          */
  1817.  
  1818.         error = rename("T:xxjunk", "T:junkdir/yyjunk");
  1819.         if (error < 0)
  1820.         perror("rename T:xxjunk to T:junkdir/yyjunk");
  1821.         else
  1822.         puts("rename succeeded, look in T:junkdir");
  1823.         return(0);
  1824.     }
  1825.  
  1826.    INPUTS
  1827.     const char *origname;        existing file
  1828.     const char *newname;        new filename and/or path
  1829.  
  1830.    RESULTS
  1831.     int error;        0 on success, a negative number on failure
  1832.  
  1833.    SEE ALSO
  1834.  
  1835.  
  1836. stdio/rewind                        stdio/rewind
  1837.  
  1838.    NAME
  1839.     rewind - seek filepointer to beginning of file
  1840.  
  1841.    SYNOPSIS
  1842.     #include <stdio.h>
  1843.  
  1844.     void rewind(fp);
  1845.     FILE *fp;
  1846.  
  1847.    FUNCTION
  1848.     rewind() rewinds the file to the beginning, equivalent to
  1849.     fseek(fp, 0L, 0);.
  1850.  
  1851.    NOTE
  1852.     refer to the file_pointer manual page for general information
  1853.  
  1854.    EXAMPLE
  1855.     /*
  1856.      *  print a file 3 times
  1857.      */
  1858.  
  1859.     #include <stdio.h>
  1860.  
  1861.     main(ac, av)
  1862.     int ac;
  1863.     char **av;
  1864.     {
  1865.         FILE *fp;
  1866.         int i;
  1867.         char buf[256];
  1868.  
  1869.         if (ac == 1) {
  1870.         puts("Expected textfile argument");
  1871.         exit(1);
  1872.         }
  1873.         fp = fopen(av[1], "r");
  1874.         if (fp == NULL) {
  1875.         printf("Unable to open %s\n", av[1]);
  1876.         exit(1);
  1877.         }
  1878.         for (i = 1; i <= 3; ++i) {
  1879.         rewind(fp);
  1880.         printf("PRINTING #%d\n", i);
  1881.         while (fgets(buf, sizeof(buf), fp))
  1882.             fputs(buf, stdout);
  1883.         }
  1884.         return(0);
  1885.     }
  1886.  
  1887.    INPUTS
  1888.     FILE *fp;        file pointer to rewind
  1889.  
  1890.    RESULTS
  1891.     none
  1892.  
  1893.    SEE ALSO
  1894.     fseek, fgetpos, fsetpos
  1895.  
  1896.  
  1897. stdio/scanf                        stdio/scanf
  1898. stdio/fscanf                        stdio/fscanf
  1899. stdio/sscanf                        stdio/sscanf
  1900.  
  1901.    NAME
  1902.     scanf    - scan formatted text from stdin
  1903.     fscanf    - scan formatted text from a specified file pointer
  1904.     sscanf    - scan formatted text from a string buffer
  1905.  
  1906.    SYNOPSIS
  1907.     #include <stdio.h>
  1908.  
  1909.     int n = scanf(ctl, ...);
  1910.     int n = fscanf(fp, ctl, ...);
  1911.     int n = sscanf(str, ctl, ...);
  1912.  
  1913.     const char *ctl;
  1914.     FILE *fp;
  1915.     char *str;
  1916.  
  1917.    FUNCTION
  1918.     *scanf() routines scan the specified input file or buffer for fields
  1919.     matching those specified in the ctl field.
  1920.  
  1921.     The ctl field contains % constructions that relate an argument
  1922.     pointer to the scanned text.  The ctl field may also contain other
  1923.     characters which must match the scanned text exactly, except for a
  1924.     white space character which matches one or more white space
  1925.     characters the scanned text.
  1926.  
  1927.     A % construction in the ctl string is formatted as follows:
  1928.  
  1929.         %[*][nnn][h/l/L]<conversion-specifier>
  1930.  
  1931.     (1) An optional * that tells scanf to skip the specified
  1932.         convresion (i.e. you specify no argument for this conversion).
  1933.         Skipped conversions are not included in the return count.
  1934.  
  1935.     (2) An optional integer that specifies the maximum field width.
  1936.  
  1937.     (3) An optional modifier h, l, or L:
  1938.  
  1939.         h    when used with d,i,n,o,u,x,X specifies the argument
  1940.         is a pointer to a short int rather than an int
  1941.  
  1942.         l    when used with d,i,o,u,x,X specifies the argument is
  1943.         a pointer to a long int rather than an int
  1944.  
  1945.         L    when used with e,E,f,F,G specifies the argument is
  1946.         a pointer to a long double rather than a double
  1947.  
  1948.     (4) A conversion specifier
  1949.  
  1950.         c    Convert the number of characters specified by the field
  1951.         width (default 1) into an array.  The expected argument
  1952.         is a pointer to an array of characters.
  1953.  
  1954.         d    Convert a decimal (base 10) number.  The expected argument
  1955.         is a pointer to an int.
  1956.  
  1957.         e/E/f/g
  1958.         scans a floating point number.    If the 'L' modifier is used
  1959.         a long double pointer is expected (NOT IMPLEMENTED IN DICE
  1960.         YET).  Otherwise a double is expected.
  1961.  
  1962.         i    Convert a number to an integer.  The format should be
  1963.         equivalent to that expected by strtol with a base argument
  1964.         of 0 (i.e. allows any base construction).
  1965.  
  1966.         n    This does not read any text, but stores the number of
  1967.         characters *scanf() has read up to this point into the
  1968.         integer argument.
  1969.  
  1970.         o    Convert a number to an octal integer
  1971.  
  1972.         p    Read a sequence of characters in the same format as
  1973.         printf's %p specifier and store into a pointer.  The
  1974.         corresponding argument is passed as a void **
  1975.  
  1976.         s    Read a string of non-white space characters and copy
  1977.         into the array specified by the argument.  The argument
  1978.         should be of type (char *) and have enough space to
  1979.         handle the string plus a nul terminator
  1980.  
  1981.         x    Read a base 16 number (hex) and copy into the passed
  1982.         integer.  This is equivalent to calling strtol with
  1983.         a base of 16.
  1984.  
  1985.         %    (i.e. %%) matches a single %
  1986.  
  1987.         [/] Scan a scanset.  Scan the input stream and place the
  1988.         characters into a char * buffer until a character is read
  1989.         that does not match the scanset.
  1990.  
  1991.         If a scan set begins with ^ (as in [^abcd]) then all
  1992.         characters are allowed EXCEPT those specified in the
  1993.         scanset.  If a scanset begins as []abcd] or [^]abcd] then
  1994.         the ']' character is included in the scan set and the
  1995.         set is terminated by the next ']' character.
  1996.  
  1997.    NOTE
  1998.     refer to the file_pointer manual page for general information
  1999.  
  2000.     all pointers to floating point storage MUST be pointers to
  2001.     doubles.
  2002.  
  2003.    EXAMPLE
  2004.     /*
  2005.      *  NOTE:   unscanned arguments are NOT cleared and will print out
  2006.      *        as garbage.
  2007.      */
  2008.  
  2009.     #include <stdio.h>
  2010.  
  2011.     main(ac, av)
  2012.     int ac;
  2013.     char *av[];
  2014.     {
  2015.         short a[4];
  2016.         int b[2];
  2017.         char buf1[32];
  2018.         char buf2[32];
  2019.         int n;
  2020.  
  2021.         if (ac != 2) {
  2022.         puts("Expected string to format!");
  2023.         exit(1);
  2024.         }
  2025.         n = sscanf(av[1], "%hd %ho %hi %*hn%d %X %10c%10c",
  2026.         a + 0, a + 1, a + 2, b + 0, b + 1,
  2027.         buf1, buf2
  2028.         );
  2029.         printf("n = %d\n", n);
  2030.         printf("a: %d %d %d %d\n", a[0], a[1], a[2], a[3]);
  2031.         printf("b: %d %d\n", b[0], b[1]);
  2032.         printf("buf1: %s\n", buf1);
  2033.         printf("buf2: %s\n", buf2);
  2034.         return(0);
  2035.     }
  2036.  
  2037.     1> t:x "123 23 01000 22 0xFF abcdefghijklm as ds sd "
  2038.     n = 7
  2039.     a: 123 19 512 12
  2040.     b: 22 255
  2041.     buf1: abcdefghij
  2042.     buf2: klm as ds
  2043.  
  2044.     1>
  2045.  
  2046.    INPUTS
  2047.     char *ctl;        format control string
  2048.     FILE *fp;        (fscanf) file pointer, (read to obtain text to format)
  2049.     char *str;        (sscanf) string pointer, text to format
  2050.  
  2051.    RESULTS
  2052.     int n;            # of conversions that occured, -1 if no conversions
  2053.                 could be done (usually means EOF).  May return
  2054.                 less than the number requested and this value does
  2055.                 not reflect any %* forms.
  2056.  
  2057.    SEE ALSO
  2058.     sprintf, printf, fprintf
  2059.  
  2060.  
  2061. stdio/setbuf                        stdio/setbuf
  2062.  
  2063.    NAME
  2064.     setbuf - set alternative stream buffer
  2065.  
  2066.    SYNOPSIS
  2067.     #include <stdio.h>
  2068.  
  2069.     void setbuf(fp, buf);
  2070.     FILE *fp;
  2071.     char *buf;
  2072.  
  2073.    FUNCTION
  2074.     setbuf() changes the internal buffer used by stdio.  The buffer you
  2075.     pass it must be BUFSIZ bytes in size.  You can set a file pointer
  2076.     to unbuffered by passing NULL for your buffer.
  2077.  
  2078.     setvbuf() superceeds this call and is, in general, a better routine.
  2079.  
  2080.    NOTE
  2081.     refer to the file_pointer manual page for general information
  2082.  
  2083.                     !!
  2084.  
  2085.     if buffering is turned off for a file pointer representing a
  2086.     console device, the console device is set to unbuffered as well.
  2087.  
  2088.    EXAMPLE
  2089.     #include <stdio.h>
  2090.  
  2091.     main()
  2092.     {
  2093.         setbuf(stdout, NULL);
  2094.  
  2095.         printf("This will print immediately because");
  2096.         sleep(1);
  2097.         printf(" we are unbuffered");
  2098.         sleep(1);
  2099.         puts("");
  2100.         return(0);
  2101.     }
  2102.  
  2103.    INPUTS
  2104.     FILE *fp;        file pointer to rewind
  2105.  
  2106.     char *buf;        buffer the file pointer uses instead of its
  2107.                 own or NULL to make the file pointer unbuffered.
  2108.  
  2109.    RESULTS
  2110.     none
  2111.  
  2112.    SEE ALSO
  2113.     setvbuf
  2114.  
  2115.  
  2116. stdio/setvbuf                        stdio/setvbuf
  2117.  
  2118.    NAME
  2119.     setvbuf - change file pointer's buffering
  2120.  
  2121.    SYNOPSIS
  2122.     #include <stdio.h>
  2123.  
  2124.     int error = setvbuf(fp, buf, mode, size);
  2125.     FILE *fp;
  2126.     char *buf;
  2127.     int mode;
  2128.     size_t size;
  2129.  
  2130.    FUNCTION
  2131.     setvbuf() changes the internal buffer used by stdio.  You may specify
  2132.     a new buffer of any size, change the buffering mode of the file
  2133.     pointer to fully buffered, line buffered, or unbuffered.
  2134.  
  2135.     mode:
  2136.         _IOFBF  fully buffered (output flushed only if buffer full)
  2137.         _IOLBF  line buffered (output flushed every newline)
  2138.         _IONBF  unbuffered (no buffering at all)
  2139.  
  2140.     For _IOFBF and _IOLBF, buf should point to the buffer you wish the
  2141.     file pointer to use and size should be the size of that buffer (any
  2142.     size other than 0 is valid).
  2143.  
  2144.     For_IONBF the buf and size arguments should be passed as NULL
  2145.  
  2146.    NOTE
  2147.                     !!
  2148.  
  2149.     If buffering is turned off for a file pointer representing a
  2150.     console device, the console device is set to unbuffered as well.
  2151.  
  2152.     If buffering is turned on for a file pointer representing a
  2153.     console device, the console device is set to buffered as well.
  2154.  
  2155.    EXAMPLE
  2156.     #include <stdio.h>
  2157.  
  2158.     main()
  2159.     {
  2160.         int c;
  2161.         static char iobuf[128];
  2162.         char buf[256];
  2163.  
  2164.         setvbuf(stdin, NULL, _IONBF, 0);
  2165.  
  2166.         printf("Type a character: ");
  2167.         fflush(stdout);
  2168.         c = getchar();
  2169.         printf("c = %d\n", c);
  2170.  
  2171.         setvbuf(stdin, iobuf, _IOLBF, sizeof(iobuf));
  2172.  
  2173.         printf("Type a line: ");
  2174.         fflush(stdout);
  2175.         gets(buf);
  2176.         printf("You said: %s\n", buf);
  2177.  
  2178.         return(0);
  2179.     }
  2180.  
  2181.    INPUTS
  2182.     FILE *fp;        file pointer to change buffering options on
  2183.     char *buf;        new buffer or NULL (_IONBF)
  2184.     int mode;        buffering mode
  2185.     size_t size;        size of new buffer if not NULL, else 0
  2186.  
  2187.    RESULTS
  2188.     int error;        0 on success, a negative number on error
  2189.                 (such as illegal arguments)
  2190.  
  2191.    SEE ALSO
  2192.     setbuf
  2193.  
  2194.  
  2195. stdio/stdin                        stdio/stdin
  2196. stdio/stdout                        stdio/stdout
  2197. stdio/stderr                        stdio/stderr
  2198.  
  2199.    NAME
  2200.     stdin  - standard input channel (file pointer - MACRO)
  2201.     stdout - standard output channel (file pointer - MACRO)
  2202.     stderr - standard error channel (file pointer - MACRO)
  2203.  
  2204.    SYNOPSIS
  2205.     #include <stdio.h>
  2206.  
  2207.  
  2208.    FUNCTION
  2209.     stdin is a FILE * type that represents the program's standard
  2210.     input stream.  This can be redirected via command line redirection
  2211.     when the program is run.
  2212.  
  2213.     stdout is a FILE * type that represents the program's standard
  2214.     output stream.    This can also be redirected via command line
  2215.     redirection when the program is run.
  2216.  
  2217.     stderr is a FILE * type that represents the program's standard
  2218.     error stream.  Currently stderr is openned by _main and represents
  2219.     the console device associated with the program regardless of
  2220.     standard redirections.
  2221.  
  2222.     These file pointers may be fclose()d or freopen()d at any time.
  2223.     The stdio macros getchar() and putchar() and stdio library
  2224.     routines gets() and puts() deal with stdin and stdout
  2225.     respectively while other library routines such as perror() output
  2226.     to stderr.
  2227.  
  2228.    SEE ALSO
  2229.     gets, puts, getchar, putchar, perror
  2230.  
  2231.  
  2232. stdio/tmpfile                        stdio/tmpfile
  2233.  
  2234.    NAME
  2235.     tmpfile - create a temporary file
  2236.  
  2237.    SYNOPSIS
  2238.     #include <stdio.h>
  2239.  
  2240.     FILE *fp = tmpfile(void);
  2241.  
  2242.    FUNCTION
  2243.     The tmpfile() call creates a temporary file and returns a
  2244.     file pointer.  The name of the file is not accessable.    The
  2245.     file pointer is available or reading, writing, and seeking (as in
  2246.     rewind, fseek).  The file is initially empty.
  2247.  
  2248.     This call may be used to create a temporary file that will
  2249.     automatically be remove()d when you fclose() it.  tmpfile() returns
  2250.     a FILE * pointer or NULL if it was unable to create the file.
  2251.  
  2252.    EXAMPLE
  2253.     #include <stdio.h>
  2254.     #include <assert.h>
  2255.  
  2256.     main()
  2257.     {
  2258.         FILE *fp = tmpfile();
  2259.         char buf[256];
  2260.  
  2261.         assert(fp);
  2262.  
  2263.         fputs("This is a test of\n"
  2264.           "a temporary file\n"
  2265.           "fubar bletch\n",
  2266.           fp
  2267.         );
  2268.         rewind(fp);
  2269.         while (fgets(buf, sizeof(buf), fp)) {
  2270.         fputs(buf, stdout);
  2271.         }
  2272.         fclose(fp);     /*  close and delete the file   */
  2273.         return(0);
  2274.     }
  2275.  
  2276.    INPUTS
  2277.     none
  2278.  
  2279.    RESULTS
  2280.     FILE *fp;        openned temporary file
  2281.  
  2282.    SEE ALSO
  2283.     tmpnam, fopen, fclose
  2284.  
  2285.  
  2286. stdio/tmpnam                        stdio/tmpnam
  2287.  
  2288.    NAME
  2289.     tmpnam - create a unique, temporary file name
  2290.  
  2291.    SYNOPSIS
  2292.     #include <stdio.h>
  2293.  
  2294.     char *filename = tmpnam(buf);
  2295.     char *buf;
  2296.  
  2297.    FUNCTION
  2298.     tmpnam() creates a unique temporary file name meant to never
  2299.     be seen by the user.  The filename tmpnam() creates will be
  2300.     no more than L_tmpnam bytes long (L_tmpnam is a macro in <stdio.h>),
  2301.     including the nul so you can simply declare a buffer:
  2302.  
  2303.         char buf[L_tmpnam];
  2304.  
  2305.     tmpnam() returns the buffer into which it created the temporary
  2306.     file name.  If you specify a non-NULL buffer it returns its first
  2307.     argument.
  2308.  
  2309.     If you pass NULL to tmpnam() then tmpnam() will use its down internal
  2310.     static buffer (overwritting any previous name that was stored in
  2311.     said buffer) and return a pointer to that.
  2312.  
  2313.    EXAMPLE
  2314.     #include <stdio.h>
  2315.     #include <assert.h>
  2316.  
  2317.     main()
  2318.     {
  2319.         char buf[L_tmpnam];
  2320.         char *ptr;
  2321.  
  2322.         ptr = tmpnam(NULL);
  2323.         puts(ptr);
  2324.  
  2325.         assert(tmpnam(buf) == buf);     /*  returns argument */
  2326.         puts(buf);
  2327.  
  2328.                         /*    haven't overwritten it yet */
  2329.         printf("%s (same as first)\n", ptr);
  2330.  
  2331.         assert(tmpnam(NULL) == ptr);    /*  that will overwrite it!    */
  2332.         puts(ptr);
  2333.  
  2334.         return(0);
  2335.     }
  2336.  
  2337.    INPUTS
  2338.     char *buf;        optional buffer of at least L_tmpnam bytes to
  2339.                 hold the temporary file name or NULL to have
  2340.                 tmpnam() use its own internal buffer.
  2341.  
  2342.    RESULTS
  2343.     char *ptr;        pointer to buffer (buf if buf != NULL)
  2344.  
  2345.    SEE ALSO
  2346.     tmpfile
  2347.  
  2348.  
  2349. stdio/ungetc                        stdio/ungetc
  2350.  
  2351.    NAME
  2352.     ungetc - push a character back onto a file pointer's input stream
  2353.  
  2354.    SYNOPSIS
  2355.     #include <stdio.h>
  2356.  
  2357.     int r = ungetc(c, fp);
  2358.     int c;
  2359.     FILE *fp;
  2360.  
  2361.    FUNCTION
  2362.     ungetc() pushes the specified character back onto the input stream,
  2363.     as if it had not been read.  Only ONE character may be pushed back
  2364.     onto an input stream at a time.  If all went well, the return value
  2365.     r is equal to c.  Else EOF is returned if too many characters were
  2366.     pushed back.
  2367.  
  2368.     Some implementations of C allow multiple characters to be pushed
  2369.     back.  The majority, including DICE, allows only one.
  2370.  
  2371.     ungetc() is useful when, in scanning an input stream, you overshoot
  2372.     the 'last' character you wanted a particular routine to retrieve.
  2373.     This routine can push the character back onto the input stream
  2374.     with ungetc() so another routine's getc() (getchar(), fread(), fgetc(),
  2375.     etc...) will get that character back.
  2376.  
  2377.    EXAMPLE
  2378.     #include <stdio.h>
  2379.     #include <ctype.h>
  2380.  
  2381.     main()
  2382.     {
  2383.         char buf[256];
  2384.         void scan_number();
  2385.         void scan_alpha();
  2386.  
  2387.         puts("Enter nnnaaannn where n=digit a=alpha.  Example:   1234abcd99");
  2388.         printf("? ");
  2389.         fflush(stdout);
  2390.         scan_number();
  2391.         puts("--");
  2392.         scan_alpha();
  2393.         puts("--");
  2394.         scan_number();
  2395.         return(0);
  2396.     }
  2397.  
  2398.     static void
  2399.     scan_number()
  2400.     {
  2401.         short c;
  2402.  
  2403.         for (c = getchar(); c >= '0' && c <= '9'; c = getchar()) {
  2404.         printf("digit: %c\n", c);
  2405.         }
  2406.         if (c != EOF)
  2407.         ungetc(c, stdin);
  2408.     }
  2409.  
  2410.     static void
  2411.     scan_alpha()
  2412.     {
  2413.         short c;
  2414.  
  2415.         for (c = getchar(); tolower(c) >= 'a' && tolower(c) <= 'z'; c = getchar()) {
  2416.         printf("alpha: %c\n", c);
  2417.         }
  2418.         if (c != EOF)
  2419.         ungetc(c, stdin);
  2420.     }
  2421.  
  2422.  
  2423.     1> testprg
  2424.     Enter nnnaaannn where n=digit a=alpha.    Example:   1234abcd99
  2425.     ? 98charlie55
  2426.     digit: 9
  2427.     digit: 8
  2428.     --
  2429.     alpha: c
  2430.     alpha: h
  2431.     alpha: a
  2432.     alpha: r
  2433.     alpha: l
  2434.     alpha: i
  2435.     alpha: e
  2436.     --
  2437.     digit: 5
  2438.     digit: 5
  2439.  
  2440.     1>
  2441.  
  2442.  
  2443.    INPUTS
  2444.     int c;            character to push back onto input stream
  2445.     FILE *fp;        file pointer stream to push character on to.
  2446.  
  2447.    RESULTS
  2448.     int r;            pushed character (c) if no error, EOF if error
  2449.  
  2450.    SEE ALSO
  2451.     getc, getchar, fread, fgetc
  2452.  
  2453.  
  2454.